---
title: 图片与资源 API 参考
sidebar:
  label: 'astro:assets'
i18nReady: true
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 6
---
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro';

<p><Since v="3.0.0" /></p>

Astro 提供了内置组件和辅助函数来优化和显示图像。有关功能和使用示例，[请参阅我们的图像指南](/zh-cn/guides/images/)。

## 从 `astro:assets` 导入

```js
import { 
  Image,
  Picture,
  getImage,
  inferRemoteSize,
 } from 'astro:assets';
```

### `<Image />`

`<Image />` 组件能优化并转换图像。

该组件还可用于创建能根据容器尺寸或设备屏幕大小及分辨率自动调整的 [响应式图片](#响应式图片属性) 。

```astro title="src/components/MyComponent.astro"
---
// 导入图像组件和图片
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 图片分辨率是 1600x900
---

<!-- `alt` 在 Image 组件中是必需的属性 -->
<Image src={myImage} alt="A description of my image." />
```

```html
<!-- 输出 -->
<!-- Image 组件已经过优化，并且对应的属性也被强制使用。 -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="一段关于我图片的描述。"
/>
```

#### Image 属性

`<Image />` 组件除接受 HTML `<img>` 标签的所有属性外，还支持以下列出的属性及 [响应式图片属性](#响应式图片属性)。

##### src (必须)

<p>

**类型：** `ImageMetadata | string | Promise<{ default: ImageMetadata }>`
</p>

图像文件的 `src` 值的格式取决于图像文件的位置：

- **`src/` 中的本地图像** - 你必须**同时导入图像**，使用相对文件路径或配置并使用 [导入别名](/zh-cn/guides/imports/#别名)。然后使用导入名称作为 `src` 值：

  ```astro title="src/pages/index.astro" "myImportedImage" "{myImportedImage}"
  ---
  import { Image } from 'astro:assets';
  import myImportedImage from '../assets/my-local-image.png';
  ---
  <Image src={myImportedImage} alt="descriptive text" />
  ```

- **`public/` 文件夹中的图像** - 使用图像相对于 `public` 文件夹的**文件路径**作为属性值：

  ```astro title="src/pages/index.astro" '"/images/my-public-image.png"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image 
    src="/images/my-public-image.png"
    alt="descriptive text"
    width="200"
    height="150" 
  />
  ```

- **远程图像** - 使用图像的**完整 URL**作为属性值：

  ```astro title="src/pages/index.astro" '"https://example.com/remote-image.jpg"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image 
    src="https://example.com/remote-image.jpg"
    alt="descriptive text"
    width="200"
    height="150"
  />
  ```

##### alt (必须)

<p>

**类型：** `string`
</p>

使用必需的 `alt` 属性为图像提供 [描述性的 alt 文本](https://www.w3.org/WAI/tutorials/images/)。

如果图像仅仅是装饰性的（即对理解页面没有帮助），请设置 `alt=""` 以便屏幕阅读器和其他辅助技术知道忽略该图像。

##### width 和 height（对于 `public/` 中的图像是必须的）

<p>

**类型：** `number | undefined`
</p>

这些属性定义了要用于图像的尺寸。

当设置了 `layout` 类型时，这些属性会根据图像尺寸自动生成，在大多数情况下不应手动设置。

当使用保持原始宽高比的图像时，`width` 和 `height` 是可选的。这些尺寸可以自动从位于 `src/` 中的图像文件自动推断出来。而对于远程图像，请将 `<Image />` 或 `<Picture />` 组件上的 [`inferSize` 属性设置为 `true`](#infersize)，或使用 [`inferRemoteSize()`](#inferremotesize) 函数。

但是，对于存储在你的 `public/` 文件夹中的图像，这两个属性都是必需的，因为 Astro 无法分析这些文件。

##### densities

<p>

**类型：** ``(number | `${number}x`)[] | undefined``<br />
<Since v="3.3.0" />
</p>

为图像生成的像素密度列表。

`densities` 属性与设置了 `layout` 属性或 `image.layout` 配置的 [响应式图像](#响应式图片属性) 不兼容，若同时设置将被忽略。

如果提供了该值，将会在 `<img>` 标签上生成一个 `srcset` 属性。在使用此值时，请不要提供 `widths` 的值。

与原始图像相同或大于原始图像宽度的像素密度会被忽略，以避免放大图像。

```astro title="src/components/MyComponent.astro"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image 
  src={myImage}
  width={myImage.width / 2}
  densities={[1.5, 2]}
  alt="我的图片描述"
/>
```

```html
<!-- 输出 -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="我的图片描述"
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
```

##### widths

<p>

**类型：** `number[] | undefined`<br />
<Since v="3.3.0" />
</p>

为图像生成的宽度列表。

如果提供了该值，将会在 `<img>` 标签上生成一个 `srcset` 属性。但还需提供一个 [`sizes` 属性](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes)。

`widths` 和 `sizes` 属性将通过 `layout` 属性自动生成，用于响应式图像。通常无需提供这些值，但可用于覆盖任何自动生成的值。

在使用该值时，请不要提供 `densities` 的值。这两个值只能选择一个来生成 `srcset` 属性。

将忽略大于原始图像宽度的宽度值，以避免对图像进行放大。

```astro title="src/components/MyComponent.astro"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 1600x900
---
<Image
  src={myImage}
  widths={[240, 540, 720, myImage.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}
  alt="我的图片描述"
/>
```

```html
<!-- 输出 -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 240w,
    /_astro/my_image.hash.webp 540w,
    /_astro/my_image.hash.webp 720w,
		/_astro/my_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="我的图片描述"
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>
```

##### sizes

<p>

**类型：** `string | undefined`<br />
<Since v="3.3.0" />
</p>

指定图像在各类媒体查询条件下的布局宽度。在指定 `widths` 时必须提供此参数。

响应式图片的 `widths` 和 `sizes` 属性将通过布局属性自动生成。通常无需手动提供这些值，但可用于覆盖任何自动生成的值。

针对 `constrained` 和 `full-width` 图片自动生成的 `sizes` 属性，其计算前提是当视口宽度小于图片宽度时，图片会以接近屏幕全宽的方式显示。若实际布局与此存在显著差异（例如在小屏幕设备上采用多栏布局），则可能需要手动调整 `sizes` 属性以获得最佳效果。

##### format

<p>

**类型：** `ImageOutputFormat | undefined`
</p>

你可以选择指定要使用的 [图像文件类型](https://developer.mozilla.org/zh-CN/docs/Web/Media/Formats/Image_types#common_image_file_types) 输出。

默认情况下，`<Image />` 组件将生成 `.webp` 文件。

##### quality

<p>

**类型：** `ImageQuality | undefined`
</p>

`quality` 是一个可选属性，可以是：
- 一个预设值（`low`、`mid`、`high`、`max`），可以在不同格式之间自动标准化。
- 一个从 `0` 到 `100` 的数字（不同格式之间的表现不同）。

##### inferSize

<p>

**类型：** `boolean`<br />
**默认值：** `false`<br />
<Since v="4.4.0" />
</p>

允许你自动设置远程图像的原始 `width` 和 `height`。

默认情况下，这个值被设置为 `false`，你必须手动指定远程图片的宽度和高度。

在 `<Image />` 组件中添加 `inferSize`（或者在 `getImage()` 中添加 `inferSize: true`），以便在获取时从图片内容中推断这些值。如果你不知道远程图片的尺寸，或者这些尺寸可能会变化，这个属性对你会很有帮助：

```astro title="src/components/MyComponent.astro" "inferSize"
---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="一只猫在阳光下睡觉。" />
```

`inferSize` 能够获取来自未经授权域的 [远程图片的尺寸](/zh-cn/guides/images/#授权远程图像)，但图片本身将保持未处理状态。


##### priority

<p>

**类型：** `boolean`<br />
**默认值：** `false`<br />
<Since v="5.10.0" />
</p>

可自动为首屏图片设置 `loading`、`decoding`，和 `fetchpriority` 属性至最佳值。

```astro title="src/components/MyComponent.astro" "priority"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} priority alt="A description of my image" />
```

当在 `<Image />` 或 `<Picture />` 组件中添加 `priority="true"`（或简写语法 `priority` ）时，它将添加以下属性以指示浏览器立即加载图像：

```html
loading="eager"
decoding="sync"
fetchpriority="high"
```

如需进一步定制，这些独立属性仍可手动设置。

### `<Picture />`

<p><Since v="3.3.0" /></p>

 `<Picture />` 组件可以生成具有多种格式和（或）尺寸的优化后的图像。
 
该组件还可用于创建能根据容器尺寸或设备屏幕大小及分辨率自动调整的 [响应式图片](#响应式图片属性) 。

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 图像的分辨率为 1600x900
---

<!-- 在图片组件上 `alt` 属性是必需的 -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />
```

```html
<!-- 输出 -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>
```

#### Picture 属性

`<Picture />` 接受 [`<Image />` 组件](#image-属性) 的所有属性（包括 [响应式图片属性](#响应式图片属性)），以及以下属性：

##### `formats`

<p>

**类型：** `ImageOutputFormat[]`
</p>

一个图像格式的数组，用于 `<source>` 标签。数组内的元素将按照列出的顺序添加为 `<source>` 元素，并且此顺序决定显示哪种格式。为了获得最佳性能，请首先列出最现代化的格式（例如 `webp` 或 `avif`）。默认情况下，它被设置为 `['webp']`。

##### `fallbackFormat`

<p>

**类型：** `ImageOutputFormat`
</p>

用于作为 `<img>` 标签的回退值的格式。对于静态图像，默认为 `.png`（如果图像是 JPG，则默认为 `.jpg`）；对于动画图像，默认为 `.gif`；对于 SVG 文件，默认为 `.svg`。

##### `pictureAttributes`

<p>

**类型：** `HTMLAttributes<'picture'>`
</p>

一个被添加到 `<picture>` 标签的属性对象。

使用该属性可将属性应用于外部的 `<picture>` 元素本身。除了用于图像转换的属性外，直接应用于 `<Picture />` 组件的属性将应用于内部的 `<img>` 元素。

```astro title="src/components/MyComponent.astro"
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // Image 为 1600x900
---

<Picture
  src={myImage}
  alt="我的图片描述。"
  pictureAttributes={{ style: "background-color: red;" }}
/>
```

```html
<!-- 输出 -->
<picture style="background-color: red;">
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    alt="我的图片描述。"
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>
```

### 响应式图片属性

在 [`<Image />`](#image-) 或 [`<Picture />`](#picture-) 组件上设置 [`layout`](#layout) 属性会创建一个响应式图片，并启用其他属性设置。

```astro title=MyComponent.astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="我的图片描述。" layout='constrained' width={800} height={600} />
```

设置布局后，会根据图片的尺寸和布局类型自动生成 `srcset` 和 `sizes` 属性。前面的 `<Image />` 组件将生成以下 HTML 输出：

```html
<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="我的图片描述"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>
```
`layout` 的值还定义了应用于 `<img>` 标签的默认样式，以确定图片应如何根据其容器调整大小：

```css title="响应式图片样式"
:where([data-astro-image]) {
	object-fit: var(--fit);
	object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
	width: 100%;
}
:where([data-astro-image='constrained']) {
	max-width: 100%;
}
```

你可以通过在 `<Image />` 或 `<Picture />` 组件上设置 [`fit`](#fit) 和 [`position`](#position) 属性来覆盖默认的 `object-fit` 和 `object-position` 样式。


##### layout

<p>

**类型：** `'constrained' | 'full-width' | 'fixed' | 'none'` <br />
**默认值：** `image.layout | 'none'` <br />
<Since v="5.10.0" />
</p>

定义一个[响应式图片](#响应式图片属性)，并确定当容器大小改变时图片应如何调整大小。可用于覆盖 [`image.layout`](/zh-cn/reference/configuration-reference/#imagelayout) 的默认配置值。

- `constrained` - 图片将按比例缩小以适应容器，保持其宽高比，但不会放大超过指定的 `width` 和 `height` 或图片的原始尺寸。

  如果你希望图片在可能的情况下以请求的尺寸显示，但在较小的屏幕上收缩以适应，请使用此选项。这与使用 Tailwind 时图片的默认行为相匹配。如果你不确定，这可能是你应该选择的布局。

- `full-width` - 图片将按比例缩放以适应容器的宽度，保持其宽高比。

  用于主视觉图片或其他应占据页面整个宽度的图片。

- `fixed` - 图片将保持请求的尺寸并且不会调整大小。它会生成一个 `srcset` 以支持高密度显示，但不会为不同的屏幕尺寸生成。

  如果图片不会调整大小，例如图标或小于任何屏幕宽度的徽标，或其他固定宽度容器中的图片，请使用此选项。

- `none` - 图片将不是响应式的。不会自动生成 `srcset` 或 `sizes`，也不会应用任何样式。

  如果你已启用默认布局，但希望为特定图片禁用它，这很有用。

例如，将 `constrained` 设置为默认布局，你可以覆盖任何单个图片的 `layout` 属性：

```astro title="src/components/MyComponent.astro"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="这将使用 constrained 布局" width={800} height={600} />
<Image src={myImage} alt="这将使用 full-width 布局" layout="full-width" />
<Image src={myImage} alt="这将禁用响应式图片" layout="none" />
```

##### fit

<p>

**类型：** `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'` <br />
**默认值：** `image.objectFit | 'cover'` <br />
<Since v="5.10.0" />
</p>

当设置或配置了 [`layout`](#layout) 属性时启用。定义当宽高比改变时，响应式图片应如何裁剪。

值与 CSS `object-fit` 的值相匹配。默认为 `cover`，如果设置了，则为 [`image.objectFit`](/zh-cn/reference/configuration-reference/#imageobjectfit) 的值。可用于覆盖默认的 `object-fit` 样式。

##### position

<p>

**类型：** `string` <br />
**默认值：** `image.objectPosition | 'center'` <br />
<Since v="5.10.0" />
</p>

当设置或配置了 [`layout`](#layout) 属性时启用。定义当宽高比改变时，响应式图片的裁剪位置。

值与 CSS `object-position` 的值相匹配。默认为 `center`，如果设置了，则为 [`image.objectPosition`](/zh-cn/reference/configuration-reference/#imageobjectposition) 的值。可用于覆盖默认的 `object-position` 样式。

### `getImage()`

<p>

**类型：**`(options: UnresolvedImageTransform) => Promise<GetImageResult>`
</p>

:::caution
`getImage()` 依赖于仅在服务器上可用的 API，当在客户端使用时会导致构建失败。
:::

`getImage()`函数旨在生成用于在 HTML 之外的其他地方所使用的图像，例如在 [API 路由](/zh-cn/guides/endpoints/#服务器端点api-路由) 中。它还允许你创建自定义的 `<Image />` 组件。

`getImage()` 函数接受一个选项对象，其中包含与 [Image 组件相同的属性](#image-属性)（除了 `alt`）。

```astro
---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>
```

它返回了一个具有以下类型的对象：

```js
type GetImageResult = {
  /* 渲染图像所需的附加 HTML 属性（宽度、高度、样式等） */
  attributes: Record<string, any>;
  /* 已通过校验的参数 */
  options: ImageTransform;
  /* 传递的原始参数 */
  rawOptions: ImageTransform;
  /* 生成图像的路径 */
  src: string;
  srcSet: {
    /* 为 srcset 生成值，每个条目都有一个 url 和一个 size */
    values: SrcSetValue[];
    /* 准备在`srcset`属性中使用的值 */
    attribute: string;
  };
}
```

### inferRemoteSize()

<p>

**类型：** `(url: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>`<br />
<Since v="4.12.0" />
</p>

推断远程图像​​尺寸的函数。它可以作为传递 `inferSize` 属性的替代方法。

```ts
import { inferRemoteSize } from 'astro:assets';
const {width, height} = await inferRemoteSize("https://example.com/cat.png");
```
